Skip to main content
Version: 2025.09

API Reference

The Istari Digital Model Concept Protocol (MCP) Service provides structured access to system, resource, and job operations within the Istari platform.

It is organized into three categories:

  • System Tools: Manage systems, snapshots, and configurations.
  • Resource Tools: Handle models and artifacts.
  • Job Tools: Run automated analysis and processing.

System Tools​

Search for Systems​

Find existing systems by name, ID, or other criteria to discover what's available before working with them.

Use this to:

  • Find or list existing systems
  • Search systems by name or ID
  • Filter by archive status (Active/Archived)
  • Browse systems you've created

Input Parameters:

  • system_id (optional): Exact system IDs to match
  • name (optional): Case-insensitive substring search over system names
  • page (optional): Page number (≥1, used only when no local filters)
  • size (optional): Page size (1-100, used only when no local filters)
  • filter_by (optional): 'created_by_id' or '-created_by_id'
  • archive_status (optional): ["Active"], ["Archived"], or ["Active","Archived"]
  • sort (optional): "created" (ascending) or "-created" (descending)

Returns: PageSystem with matching systems and pagination metadata

Search System Files​

List all files tracked within a specific system's snapshot to explore system contents.

Use this to:

  • See what files are tracked within a system
  • Explore the contents of a system's snapshot
  • Filter by filename or file extension
  • Find specific files within a system

Input Parameters:

  • system_id (required): System ID whose snapshot revisions to list
  • snapshot_id (optional): Specific snapshot ID (defaults to baseline if omitted)
  • page (optional): Page number
  • size (optional): Page size (default 100)
  • name (optional): Filename substring filters
  • extension (optional): File extension filters (e.g., ['.xlsx', '.csv'])
  • sort (optional): "created" (ascending) or "-created" (descending)

Returns: PageSnapshotRevisionSearchItem with file revisions and metadata

Create a New System​

Create a new engineered system to organize related engineering files and configurations.

Use this to:

  • Create a new engineered system
  • Start organizing files for a new project or product
  • Set up a container for related engineering artifacts

Input Parameters:

  • name (required): System name
  • description (optional): Optional description for the new system

Returns: System object with ID, name, description, and metadata

Update a System​

Modify an existing system's metadata such as name or description.

Use this to:

  • Rename an existing system
  • Update or clarify a system's description
  • Modify system metadata without affecting its contents

Input Parameters:

  • system_id (required): Target system ID to update
  • name (optional): New name (only provided fields are updated)
  • description (optional): New description (only provided fields are updated)

Returns: Updated System object with modified metadata

List System Snapshots​

View snapshots/versions of systems or configurations to track version history.

Use this to:

  • See snapshots/versions of a system or configuration
  • Browse version history
  • Find specific snapshots by tag (like "baseline")
  • Track changes over time

Input Parameters:

  • system_id (optional): Filter snapshots by system ID
  • configuration_id (optional): Filter snapshots by configuration ID
  • tag (optional): Filter by snapshot tag (e.g., 'baseline')
  • page (optional): Page number
  • size (optional): Page size
  • sort (optional): "created" (ascending) or "-created" (descending)

Returns: PageSnapshot with snapshot list and pagination metadata

Create a System Snapshot​

Generate a snapshot/checkpoint of a system configuration to preserve a point-in-time state.

Use this to:

  • Create a snapshot/checkpoint of a system configuration
  • Preserve a version for future reference
  • Establish a baseline or milestone

Input Parameters:

  • configuration_id (required): Configuration ID to snapshot

Returns: ResponseCreateSnapshot with snapshot creation details

Add Files to System​

Create a new system configuration that tracks specified existing files (sets them to LATEST version).

Use this to:

  • Attach existing files to a system
  • Track files within a system configuration
  • Build a system from previously uploaded files
  • Create a new configuration with selected files

Input Parameters:

  • system_id (required): System ID to attach files to
  • file_ids (required): List of existing file IDs to track (set to LATEST)
  • configuration_name (optional): Name for the new configuration (defaults to 'Default Configuration')

Returns: SystemConfiguration object with tracked files and metadata

Resource Tools​

Search Resources​

Search for engineering models, artifacts, comments, or jobs across the Istari registry with flexible filtering options.

Use this to:

  • Find or list engineering models, artifacts, comments, or jobs
  • Search by filename, description, version, or metadata
  • Filter by file type, creation date, or status

Input Parameters:

  • page (optional): Page number (≥1)
  • size (optional): Page size (1-100)
  • resource_id (optional): Resource IDs to match
  • type_name (optional): ["model"], ["artifact"], ["comment"], ["job"] or combinations
  • file_name (optional): File name substring filters
  • description (optional): Description substring filters
  • version_name (optional): Version name substring filters
  • external_identifier (optional): External identifier filters
  • display_name (optional): Display name substring filters
  • mime_type (optional): MIME type filters (e.g., 'text/csv')
  • file_size (optional): Exact file sizes in bytes
  • created_timestamp (optional): Creation timestamps (ISO-8601)
  • updated_timestamp (optional): Update timestamps (ISO-8601)
  • created_by_id (optional): Creator user ID filters
  • updated_by_id (optional): Last updater user ID filters
  • archive_status (optional): ["Active"], ["Archived"], or both
  • sort (optional): "created" (ascending) or "-created" (descending)

Returns: PageResourceSearchItem with matching resources and pagination metadata

Download File Contents​

Retrieve the raw file bytes for a resource using its File ID for local processing.

Use this to:

  • Download or access actual file contents
  • Get raw bytes of a file for processing or analysis
  • Retrieve files for local use or downstream processing

Input Parameters:

  • file_id (required): The ID of the resource file to retrieve

Returns: Raw binary file contents (bytes) - works with CSV, Excel, images, ZIP, JSON, etc.

Get Resource by File ID​

Retrieve the model or artifact metadata associated with a given File ID.

Use this to:

  • Get metadata about a resource when you only have a file ID
  • Understand what type of resource a file belongs to
  • Trace a file back to its full resource context

Input Parameters:

  • file_id (required): The ID of the resource file (Model.file.id or Artifact.file.id)

Returns: Model or Artifact object with full metadata, or None if not associated

Job Tools​

Run Extraction​

Execute the Istari extraction function on a model to generate artifacts and extract structured data.

Use this to:

  • Extract data, metadata, or information from CAD models or engineering files
  • Generate artifacts from models (drawings, reports, analysis data)
  • Process, analyze, or extract information from engineering files
  • Get structured information from CAD files

Supported File Types:

  • CAD files: .CATPart (CATIA), .prt (Creo)
  • Documents: .pdf, .xlsx (Excel)

Input Parameters:

  • model_id (required): Model ID to run the @istari:extract function on

Returns: Updated Model object with:

  • Generated artifacts list
  • Job execution details
  • Processing metadata
  • Updated model status

Run Update Parameters​

Execute the Istari update parameters function on a model to modify CAD parameters or design variables.

Use this to:

  • Modify parameters, dimensions, or variables in CAD models
  • Update design values or configuration settings
  • Change, update, modify, or set parameters in engineering models
  • Apply new parameter values to regenerate models

Supported File Types:

  • CAD files: .CATPart (CATIA), .prt (Creo)

Input Parameters:

  • model_id (required): Model ID to run the @istari:update_parameters function on
  • parameters (required): Dictionary of parameter names and string values to update

Returns: Updated Model object with:

  • Generated artifact (The updated CAD file)